Business Rules step

Use the Business Rules step to work with the profile structure of a document in order to check multiple business rules to determine if a document should be accepted or rejected.

This step is similar to the Cleanse step, but it is content-driven rather than structural, meaning that you can perform advanced logic and validations against parent/child field data rather than analyze field lengths and data types. The Business Rules step also serves as a powerful alternative to the Decision step because it can store multiple rules and conditions. Unlike the Decision and Route steps, each business rule is executed for the number of repeating elements that are used as inputs to that rule.

In addition to performing nested AND/OR field comparisons, you can use the map function library to produce an advanced result set to include in your conditions. If a document fails to meet the condition(s), the step aggregates the rejections for the document and allows you to configure a custom error message with dynamic content by using your defined rule inputs.

Successful documents that meet the conditions are sent down the accepted path. Failed documents that do not meet the conditions are sent down the rejected path and contain the data that entered the step. The error message is stored as a document property that you can reference for your messaging. You can then add Exception or Notify steps to force errors at the process or document level.

Execution of Business Rules

Business rules are executed in the order they are organized in the Rules list.

1. All rule inputs are calculated.

   • Fields are gathered.
   • Functions are executed.

2. Business rules are executed for each header and/or detail instance.

   • Conditions are executed.
   • Condition results are labeled as true or false.

3. Error messages for false results are aggregated.

4. The source document is first processed down the Accepted path, followed by the Rejected path.

5. If the document is rejected, an error message XML is attached as a Business Rules Result Message document property.

Business Rules step dialog

The Business Rules step dialog is used to configure a Business Rules step in a process.

• Add Rule - Used to add a business rule to the Business Rules step.

• Change Profile - Opens the Business Rule step Options dialog, which is used to set a display name for the Business Rules step or to select or create a profile representing the structure of the document coming into the Business Rules step.

  • Display Name - User-defined name to describe the Business Rules step. It might be helpful to phrase the name as a question that applying the business rule will answer, such as “US destination?” If you do not specify a display name, the step will not have a label.

  • Profile Type - Selects the profile type — either Database, EDI, Flat File, XML, or JSON.

  • Profile - Selects the profile. The profiles available for selection are of the selected Profile Type. As an alternative to selecting an existing profile, clicking Create enables you to create a profile of the selected type.

  • OK - Saves the changes, closes the dialog, and returns focus to the Business Rules step dialog.

  • Cancel - Closes the dialog without saving the changes and returns focus to the Business Rules step dialog.

  note

  The Business Rules step Options dialog also opens when a Business Rules step is dragged to the process canvas.

• Add a Field - Used to add a field for single output.

  • Alias - An alternative field name for referencing in conditions or the Error Message window.

  • Field - Used to select a field input definition from the profile.

• Add a Function - Used to add functions for variable output. Choose a standard or user-defined function from the library to manipulate one or more field inputs from the profile.

  • Alias - Alternative name for function reference for ease of use when defining function output(s).

  • Default values - Optional text boxes next to input definitions where you can set static values in the event that the input value is blank.

• Top Level Operator - Operator in the main condition that determines if group clause(s) should use AND or OR.

  • Add a Group - Link that generates another top-level group where you can create one or more nested conditions.

    • Group Level Operator - Operator in sub-group that determines if condition(s) should use AND or OR.

  • Add a Condition - Link that generates another comparison line where you can specify:

    • Static value
    • Single field output
    • Single function output

• Insert Value - Used to select fields and functions from the Inputs list.

The following operators are available when building conditions for business rules. The operators contains, does not contain, starts with, is empty, and is not empty perform string comparisons. They should not be used for numeric comparisons.

• = - Equal To

• != - Not Equal To

• < - Less Than

• > - Greater Than

• <= - Less Than or Equal To

• >= - Greater Than or Equal To

• contains - Input field contains value defined in the second input definition. (Special syntax for comparison against Static value is not required.)

• does not contain - Input field does not contain value defined in second input definition. (Special syntax for comparison against Static value is not required.)

• starts with - Input field begins with value defined in the second input definition. (Special syntax for comparison against Static value is not required.)

• is empty - Input field is not populated with any value. Use this operator in place of a blank static value to simulate the Decision step's comparison against NULL.

• is not empty - Input field is populated with a value.

You can organize the Business Rules step to the process in the following order:

Adding a Business Rules step to a process

Adding a Business Rules step to a process

You can add a Business Rules step to a process to check multiple business rules to determine if a document should be accepted or rejected.

Procedure

1. Drag the Business Rules step onto the process canvas.

   The Business Rules Step Options dialog opens.

2. Type a custom Display Name for the step.

3. In the Profile Type list, select the profile type that represents the format of the document coming into the Business Rules step. These profile types are available for selection:

   • Database
   • EDI
   • Flat File
   • XML
   • JSON

4. Select or create a Profile that represents the structure of the document that comes into the Business Rule step.

5. Click OK.

   The Business Rules step dialog opens.

6. Click Create a New Rule or the Add Rule icon.

   A new business rule appears in the list on the left and its properties can be entered on the right.

7. Select the words New Business Rule on the right and type a more meaningful name for the rule.

8. Now you can add inputs, conditions, and error messages.

   note

   It is important to define all inputs first so that you can properly configure your conditions and error messages.

9. To add each additional business rule to the step, repeat steps 6–8.

10. When you are done adding business rules, click OK.

Adding input fields and functions to a business rule

Adding input fields and functions to a business rule

Once you add a business rule and type its name, the next step is to add input fields and functions. It is important to define all inputs first, so that you can properly configure the conditions and error message.

Procedure

1. In the Business Rules Step dialog, add a business rule.

2. To add a field, click the Add arrow and select Field.

   The Add a Field dialog opens.

3. Type an alias.

   If you do not type an alias, the field that you select in the next step will appear here.

4. Click the Browse icon, select a field and click OK.

5. To add a function, click the Add arrow and select Function.

   The Add a Function dialog opens.

6. Do one of the following:

   • Click the Create New Function icon and create a map function.

   • Select a category from the list, and then select a function and click OK.

7. A different dialog opens, depending on the type of function that you selected. In some dialogs, you can enter optional aliases and select default values. In other dialogs, you can set up lookups, connector calls, or scripting.

8. Repeat steps 2-4 or 5-7 to add more fields or functions.

9. Now you can add conditions.

Adding conditions to a business rule

Adding conditions to a business rule

Once you define the inputs for a business rule, you can add its conditions.

Procedure

1. In the Business Rules Step dialog, define input fields and/or functions.

2. Select a top-level operator by clicking AND or OR.

3. Click Add a condition.

4. Select a static value, a single field output, or a single function output, then select an operator. Select a second static value, a single field output or a single function output.

When creating a condition, you have the ability to choose Static on either side of the equation and enter a hard-coded value in the next field. The output results are available in a drop-down list as well. The list includes the name of each field or function that you defined. In the event that there are multiple outputs from a function-type input, you can choose one output per condition. Each function output is listed separately.

5. Click Save.

6. Repeat steps 3-5 to add another condition.

7. To add nested conditions, click Add a group.

8. Select a group operator.

9. Repeat steps 3-5 to add a condition to the group.

10. Repeat the steps for adding conditions and groups as needed.

11. Now you can add error messages.

Adding error messages to a business rule

Adding error messages to a business rule

Once you define the inputs and conditions for a business rule, you can add its error message.

1. In the Business Rules step dialog, add a business rule, define inputs and add conditions.

2. Type the message in the Error Message window.

3. To add inputs to the error message, click the Insert Value button and select an input.

The value is represented by a number within brackets.

The value's number and the alias appear in the box below the message.

4. Click OK.

Changing a business rule

You can change the properties of an existing business rule in the Business Rules Properties dialog.

1. Select a Business Rule step and click Configure.

2. To change the label on the Business Rule step, select any rule in the list on the left, click the Change Profile icon and enter a new label.

3. To change a business rule's profile type or profile, select it in the list, click the Change Profile icon and select a new profile type and profile.

   caution

   If you change the profile type or profile, all business rules, including inputs and operations, are removed. You cannot undo this action.

4. To change the order in which the business rules are executed, in the list on the left click the icon to the left of a business rule and drag it to a new location.

5. To delete a business rule, select it in the list on the left and click the red Delete icon next to it, then click OK.

6. To edit an input field or function's alias, click it, edit it in the dialog and click OK.

7. To delete an input field or function, click the red Delete icon next to it, then click OK.

8. To edit a condition, pause on it and click Edit. Make changes and click Save.

9. To remove a condition, pause on it and click Remove.

10. To edit an error message, change the text in the Error Message window.

11. To remove a value from an error message, click the X next to it in the box below the message.

12. Click OK.

Business Rules Error Message window

The Error Message window allows you to create a custom message that can use the dynamic inputs from the Inputs list along with hard-coded message data. When you insert values from the list, they create a numerical syntax that binds to the numbered field in the lower value window.

Ensure that the number preceding the value name (Example: 1. Company) matches with the numerical syntax in the Error Message window (Example: {1}). The length of business rule error messages is limited to 10000 characters per document.

In messages, the single quote (') is a special character. The following points regarding single quotes apply only to the message text that you enter. Single quotes are not stripped if they are coming in as part of the data.

• A single quote by itself is stripped from the message. For example, the message text today's date is rendered as todays date.
• Two consecutive single quotes are rendered as a single quote. For example, the message text today''s date is rendered as today's date.
• An open single quote without a closing single quote escapes the rest of the message. For example, if the variable 1 is the time using a Date Mask of hh, and the variable 2 is the date, an example of the rendering of the message text 1 o'clock 2 would be 12 oclock {2}.
• JSON content in messages must be escaped by wrapping it with single quotes, thereby distinguishing it from a variable.

The Date Mask in a variable of type Date and Time cannot have an open single quote without a closing single quote.

• If the Date Mask contains a single quote before some text and a single quote after the text, the single quotes are treated as escape characters. They cause the text between the single quotes to appear in the message. Consider a Date and Time variable using a Date Mask of yyyy.MM.dd G 'at' HH:mm:ss z. An example of the rendering of the variable is 2012.12.18 AD at 15:08:56 PDT (with the word at appearing in the message).
• You can use a combination of single quotes and two consecutive single quotes to get the results you need. Consider a Date and Time variable using a Date Mask of hh 'o''clock' a, zzzz. An example of the rendering of the variable is 1 o'clock PM, Pacific Daylight Time.

The error message is generated for each business rule failure when the conditions are not met. If the document contains repeating detail fields, the Business Rules step iterates through each detail and reports a unique error message. After all rules are executed, the failures are aggregated and reported in an XML format.

Here is a sample error message in XML:

<business_rule_failures>
<business_rule_failure rule="Rule Name 1">Error Message 1</business_rule_failure>
<business_rule_failure rule="Rule Name 2">Error Message 2</business_rule_failure>
</business_rule_failures>

To reference the error message for the rejected document, you must use a document property parameter lookup (Document Property > Meta Information > Base > Business Rules Result Message). You can commonly add this parameter value to a Message or Notify step to report the failure to end users. Although this is similar to the result messaging for Try/Catch and Cleanse, the Business Rules*step is different in that it has the ability to aggregate multiple error messages per document.

Business Rules step example

In this example, an inbound Account XML document contains some company and contact information for an account. The company can have multiple, repeating contacts.

Example: XML input

Here is the sample XML input:

<Account>
<CompanyID>1564862</CompanyID>
<CompanyName>BockelCorp</CompanyName>
<Website>http://bockelcorp.net</Website>
<StreetAddress1>801 Cassatt Road</StreetAddress1>
<StreetAddress2>Suite 120</StreetAddress2>
<City>Montreal</City>
<State>qc</State>
<PostalCode>HEZ 39-542</PostalCode>
<Country>CA</Country>
<Phone>555-854-0700</Phone>
<Industry>Technology</Industry>
<ContactList>
<Contact>
<FirstName>Pamela</FirstName>
<LastName>Pearce</LastName>
<Email>ppearce@bockelcorp.net</Email>
</Contact>
<Contact>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<Email>jdoe@bockelcorp.net</Email>
</Contact>
</ContactList>
</Account>

The process developer wants to validate two business rules to successfully accept the document.

Business Rule 1 is named "Account State - PA". It validates that:

1. The State field in uppercase syntax is equal to "PA".
2. The Country field is equal to "USA".

Business Rule 1 is set up as follows:

• The State to Upper alias is a function input that uses the String > String to Upper function and applies the State field from the XML profile as the original string. The function output in this case is compared to a static value of "PA".

• The CountryCode is a standard profile input that is compared to a static value of "USA".

• The Company field input is used purely as an identifier in the error message.

Business Rule 2 is named "Contact - Email Check". It validates that:

1. The Email field is not blank.
2. The result of a cross-reference lookup against a set of email user codes does not identify a contact instance as UserCode 3.

Business Rule 2 was set up as follows:

• The Email field input uses the Is Not Empty operator to ensure that the field is populated.

• The cross reference table lookup function input accepts the Email field and the LastName field as inputs in order to find the UserCode. The alias was changed to better reflect the result.

• The cross reference table identifies John Doe as an invalid contact because John has UserCode 3.

The Message step captures the source Account XML document and includes the error as an embedded XML message captured from the Business Rules Result Message document property.

Note that the XML content is directly output as a parameter. If you would like to view the result messages in another format, consider doing the following:

• Add a Message step that captures the Business Rules Result Message document property as a single parameter.

• Pass the resulting document into a map that converts it from a source profile structure like the sample XML output above (without the second failure detail).

• Translate it to the desired format, such as flat file.

• If preferred, include it in a new Message step after the map, as a Current Data parameter along with other static or dynamic message details.

• Turn on the "Combine documents into a single message" check box in the final Message step to aggregate errors across documents.